============================================================== Copyright 1994 Northeast Data Corp. All Rights Reserved ============================================================== ============================================================== IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT IMPORTANT Before experimenting with the Netcom control, read the information below. The Netcom control allows you to perform network operations that disrupt network communication with your PC. Resetting the network adapter or deleting names from the NetBIOS name table indiscriminantly will destroy communication between your PC and other workstations on the network. ============================================================== Netcom Custom Control V1.2 The Netcom Custom Control implements NetBIOS general, session, and datagram support. All common NetBIOS functions are supported. This custom control can be used from C or C++ and is available from the Win 3.1 SDK Dialog Editor. The only difference between the demo version of the control and the commercial version is that the demo version displays a dialog box that allows the user to register the control with Northeast Data. There are no other functional differences. Here are the overall capabilities: - Support for all standard NetBIOS emulations. This includes NetBIOS services running on LAN Manager, LAN Server, Novell, Banyan VINES, 3COM. - Support for multiple network adapters. - Multiple Netcom controls within the same application. - Interprocess communication between applications on the same workstation. - Communication between applications running on separate workstations. - Adapter status and reset. - NetBIOS name support. - NetBIOS session support. - NetBIOS datagram support. ================= Legal Information ================= The purchaser of the NetCom Control is allowed to use it and distribute it in applications without paying any royalty, and without printing or displaying a copyright notice for the control. This only includes distribution of the NetCom Control DLL. It does not include distribution of the header file, import library, or documentation that comes with the NetCom Control. The purchaser of the NetCom Control may distribute the control DLL with applications that are networked (multiple users accessing the DLL from a file server) without paying any license fees to Northeast Data Corp. The development files for using the NetCom Control (this excludes the DLL) may only be used by the purchaser of the control. The purchaser may install the development files on his/her own machine for development purposes. These files may not be made available to any other person in any way. For use of the NetCom Control in any other fashion, the purchaser should contact Northeast Data Corp. to make special arrangements. =================== The demo version =================== (does not apply if you have purchased a licensed version) The demo version of the control will allow you to perform all functions implemented by the commercial version. The only difference is that a registration dialog box is displayed when the control is first loaded. By registering the control with Northeast Data Corp., you get: - The commercial version of the control - A telephone and FAX number for support - A Compuserve ID for support - Free maintenance release updates - A discount on major releases - More information about using NetBIOS =================== System Requirements =================== You must have a NetBIOS application service running on your PC. This requires a network adapter (etnernet, token ring, arcnet, etc.). This service must be compatible with Microsoft Windows. Microsoft Windows version 3.0 or higher. =================== Installation =================== Copy the NETCOM.DLL file to your Windows or Windows\System directory. Before starting Windows, make sure you have loaded any network services that are required for NetBIOS support. Start Windows and run the test.exe program provided with the Netcom control. =================== Programming =================== The example file for the test.exe program are built using the Microsoft NMAKE facility and the Microsoft C Compiler V8.0. You may need to make modifications to the test.mak file and source code if you are using a different compiler. You will need to include the NETCOM.H file in your source code. Refer to the contents of this file along with the following information: Your application must create a NetCom window. This can be done by using the SDK Dialog Editor and installing NETCOM.DLL as a custom control. Create a dialog box for your application and place a NetCom control on the dialog box. You can also place all other controls that you want on the dialog. Another way to use the control is to create a window in your application using "NetCom" as the window class. This class gets registered by calling the "RegisterNetCom" function as illustrated in the example program. This is only necessary if you implicitly link to the NetCom DLL. It is not necessary if you use the LoadLibrary API function to load the DLL explicitly. All communication with the NetCom control is done by sending messages to its window handle. In addition to the standard Windows messages for hiding and moving windows, these messages are provided: --------------------------------------------------------------------- Note: In the descriptions below, there are references to the "remote" workstation. If you are doing interprocess communication on your PC, "remote" refers to the other application on your PC. If you are communicating with a real remote workstation, "remote" refers to that workstation. Since the Netcom control is re-entrant, you can actually perform inter-process communication within the control itself. In other words, you can send data to "yourself". It is perfectly OK to have the Netcom control send data to and from itself or between Netcom controls in the same application. This has no value within the same application, other than allowing you to experiment with the control. --------------------------------------------------------------------- NCM_SETCOMMAND Issues a command to the control. The command is specified in wParam and is one of the following values. Unless stated otherwise, lParam is unused. The return value from this message is 0 for success, otherwise an error. The error codes are listed below. NCC_INIT Sets up the control for use by your application. This command must be executed before any other commands that perform network operations are executed. The NetCom control will check for the presence of NetBIOS and will get the permanent name from the network adapter. If you pass the address of a string buffer in lParam, NetCom will place the permanent name into the buffer. You buffer needs to be at least 17 characters long. NCC_REGISTERNAME Registers the name that you have previously set up using the NCM_SETNAME message (see below). The name will be registered as a NetBIOS UNIQUE name. The command fails if the name is already registered by anyone on the network. NCC_REGISTERGROUP Registers the name that you have previously set up using the NCM_SETNAME message (see below). The name is registered as a GROUP name. The command fails if the name is already registered on your workstation, or if another workstation has registered the name as a unique name. Group names can be used to send data to multiple workstations. NCC_SENDDATAGRAM Sends the data you have previously set up using the NCM_SETDATA message (see below). The data is sent to the name you have set up using the NCM_SETREMOTENAME message (see below). The Remote Name can be set to a unique name or a group name. The datagram is sent with the sender name you have set up using the NCM_SETNAME message. All workstations that have registered the remote name and have posted a "Receive Datagram" will receive the data.Since this is a datagram, you receive no notification that other workstations have received the data. NCC_RECEIVEDATAGRAM Sets up a "receive datagram" for the local name. You have to register a unique name or a group name before executing this command. After executing this command, control will be returned to your application. When a datagram is received, a NCN_RECEIVEDDATAGRAM notification message will be sent to your application. In order to receive another datagram after receiving one, you must issue this command again. NCC_CALL An attempt is made to establish a session with the workstation that has registered the name you have set up as a "Remote Name". The name of the caller (you) is the one you have set up as a local name. You have to register the NetName before executing this command. You do not have to register the RemoteName. Both names can be either unique or group names. Control is returned immediately to your application. When a connection is established with a remote workstation, your application will receive a notification message. NCC_LISTEN A listen is set up for the name you have set up as a Remote Name. This name must be a unique or group name that you have registered. You must also set up a local name that the remote workstation will use to call you. This command returns immediately to your application. When a remote workstation calls you, your application will receive a NCN_NEWRECSESSION notification message with the number of the "receive session" that has been established. You can use this notification to start a "receive" or a "send" to or from the remote station. NCC_SEND Data you have specified using the NCM_SETDATA message is sent to the remote workstation. Control is immediately returned to your application. When the remote workstation has received the data, the NCN_RECEIVEDDATA notification is sent to your application. You can use this notification to determine when to send the next block of data. The data is sent to the session number that was returned to you in the NCN_NEWSENDSESSION notification message. NCC_RECEIVE A wait for data is set up for the session that was returned in the NCN_NEWRECSESSION notification message. Control is immediately returned to your application. When data is received, a NCN_RECEIVEDDATA notfication message is sent to your application. In order to receive more data from the sender, you must issue another NCC_RECEIVE command. This should be done immediately to prevent the sender from timing out. NCC_HANGUPONREC Terminates the current RECEIVE SESSION. The remote workstation is notified. You can no longer receive or send data on this session. NCC_HANGUPONSEND Terminates the current SEND session. The receiving workstation, if any, is notified. You can no longer send or receive data on this session. NCC_CANCELALL Cancels all network requests. This includes all commands for sending or receiving datagrams or data. It does not clear any registered names from the name table. NCC_RESET Cancels all network requests and clears all names from the name table. USE THIS COMMAND WITH CAUTION. If you are running on a network, this command will delete all names that other workstations may be using to communicate with your workstation. The adapter will be set to the same state is was when your workstation was initially booted (before any network applications were started). NCC_DELETENAME Deletes the current local name from the NetBIOS name table. USE THIS COMMAND WITH CAUTION. Network servers and applications register network names for communication with your workstation. If you delete names that have been registered by your network applications, these applications will no longer be able to perform network operations. This command deletes a group name or unique name, depending on the name specified in the NetName property. NCC_RECEIVEANY Sets up a receive for any remote workstation attempting to send data to the current local name. This is different from the "Receive" command, which only accepts data from a workstation that has registered the name you have specified as your local name. Control is returned immediately to your application. When a remote workstation sends data, the NCM_RECEIVEDDATA notification message is sent to your application. NCC_RECEIVEANYFORANY This will set up a receive for any remote workstation sending data to any session (rather than a specified session) on your workstation. NCC_ADAPTERSTATUS Displays a dialog box containing information about the adapter indicated by the current Remote Name. If you specify "*" for the remote name, information from your own adapter will be displayed. If you specify a unique or group name, information from the first adapter that has registered the specified name will be displayed. NCC_LISTNAMES A list of names in the name table for the adapter indicated by the current Remote Name is returned. If the Remote Name is "*", you will get all the names registered on your workstation. If the remotename is set to a unique or group name, you will get the list of names registered by the first adapter on the network that has registered the specified name. You must supply a callback function in lParam. This function must accept two argument - LPSTR and int. You should use the MakeProcInstance API function to get a pointer to your callback function (which needs to be exported). The NetCom control will call your callback function once for each name in the name table. Your function should return non-zero to continue - zero to stop the enumeration. The first argument in your callback function will receive a null-terminated string that is the NetBIOS name that was found. The second argument is the name number. NCC_RECSESSSSTATUS Gets the session status for the current Receive Session number. Session status values are: 1 - Listen pending 2 - Call pending 3 - Session established 4 - Hang Up pending 5 - Hang Up complete 6 - Session aborted NCC_SENDSESSSTATUS Gets the session status for the current Send Session number. 1 - Listen pending 2 - Call pending 3 - Session established 4 - Hang Up pending 5 - Hang Up complete 6 - Session aborted NCC_RECEIVEBROADCAST Sets up a "Receive Datagram" for any workstation sending a broadcast datagram. Control returns immediately to your application. When a datagram is broadcasted by a remote workstation, the NCN_RECDATAGRAM notification message is sent to your application. You must then issue another NCC_RECEIVEBROADCAST command to receive anothere datagram. NCC_SENDBROADCAST Sends a datagram to all workstations on the network. You specify the data to send using the NCM_SETDATA message. All workstations that have posted a "Receive Broadcast Datagram" will receive the message. Since this is a datagram, your workstation will not be notified as to whether or not any workstations have received the message. NCM_SETNAME Sets the current local NetBIOS name. In order to use this name for most commands, you must issue the NCC_REGISTERNAME or NCC_REGISTERGROUP commands to register the name. You only have to register a name once - not each time you use it in a command. You specify the name as a pointer to a string in lParam. Specify the length in wParam. The maximum length of a name is 16 characters. NCM_SETREMOTENAME Sets the current Remote NetBIOS name. This name is used for various functions described above. You specify the remote name as a pointer to a string in lParam. Specify the length of the string in wParam. The maximum length of a name is 16 characters. NCM_SETSESSION If you specifiy 0 in wParam, the current RECEIVE session number is is set to the value you specify in lParam. If you specify 1 in wParam, the current SEND session number is is set to the value you specify in lParam. Session numbers are returned to you as the result of a CALL or LISTEN completion. When either of these complete, you get a NCN_NEWSENDSESSION or NCN_NEWRECSESSION notification. NCM_SENDDATA Sets the current data buffer to the buffer you point to in lParam. The length of the data is specified in wParam. The maximum data length is 128k minus 2 bytes for Send commands. The maximum length is 255 bytes for datagrams. This data is sent using the "SendDatagram", "SendBroadcast", or "Send" commands. NCM_SETTRACE If wParam is set to TRUE, diagnostic messages are displayed for every network command performed. This is useful for troubleshooting your application. Setting wParam to FALSE disables display of diagnostic messages. ===================== Notification Messages ===================== These notifications are sent to the window that owns the NetCom Custom Control window. The message is WM_COMMAND, with: wParam - The ID of the NetCom control. lParam - LOWORD - The notification message listed below. HIWORD - Depends on the notification message - described below. NCN_RECDATAGRAM HIWORD of lParam - A handle to a RECINFOSTRUCT as defined in NETCOM.H. Sent when a datagram is received. You lock the handle contained in the high word of LPARAM and cast the result to a pointer to a RECINFOSTRUCT. The structure members are: lpData - Pointer to the received data nLen - Length of the received data szFrom - The NetBIOS name used by the sender of the datagram. NCN_NEWSENDSESSION HIWORD of lParam - The number of the new session. Sent when a new session has been established as a result of issuing the "Call" command. NCN_NEWRECSESSION HIWORD of lParam - The number of the new session. Sent when a new session has been established as a result of issuing the "Listen" command. NCN_RECEIVE HIWORD of lParam - A handle to a RECINFOSTRUCT as defined in NETCOM.H. Sent when data is received on a session. You lock the handle contained in the high word of LPARAM and cast the result to a pointer to a RECINFOSTRUCT. The structure members are: lpData - Pointer to the received data nLen - Length of the received data szFrom - The number of the session the data was received on (as a string). NCN_SESSIONCLOSED HIWORD of lParam - The number of the session that has been closed. Sent when a session has been closed by the remote workstation. You can no longer issue sends or receives on this session. NCN_SENDCOMPLETE HIWORD of lParam - The number of the session that the send has completed on. A remote workstation has successfully received the data you sent in a "Send" command. This is the cue for you to send the next block of data to the remote workstation. ============================= Error Codes ============================= These are the error codes returned from messages sent to the NetCom control. These constants are defined in NETCOM.H: ERR_NONETBIOS - NetBIOS not installed ERR_ADDGROUP - Failed to add a group name ERR_ADDNAME - Failed to add a unique name ERR_SENDDATAGRAM - Send datagram failed ERR_SETUPRECEIVE - Failed to set up a receive ERR_NONAME - Name not found in NetBIOS name table ERR_NETINIT - Failed to initialize the NetBIOS ERR_DUPNAME - Duplicate name ERR_ADAPTERRESET - Failed to reset adapter ERR_HANGUP - Failed to hang up session ERR_CALL - NetBIOS CALL failed ERR_DELETENAME - Failed to delete NetBIOS name ERR_LISTEN - Failed to set up a LISTEN ERR_SEND - Failed to send data ERR_ADAPTERSTATUS - Failed to get adapter status ERR_MEMALLOC - Memory allocation failure ERR_SESSIONSTATUS - Failed to get session status ERR_SESSIONNOTFOUND - Session not found ============================= General Notes ============================= The NetCom control handles communication between your application and the NetBIOS layer. Being object-oriented, it is more than simply an interface layer. The control internally maintains information about names, sessions, and data that have been specified by your application. Your application uses the control to perform operations by first setting up appropriate information in the control, and then issuing a command to the control to make it perform a NetBIOS operation. The demo application uses most of the NetBIOS functions implemented in the Netcom control. The TRACE property is set to TRUE in the demo, so you will see many messages as commands are executed. Since many operations are asynchronous, you will see messages that appear to be out of order. For example, you may see a message indicating that a datagram has been received - followed by a message indicating that the datagram has been sent. This is normal behavior. ------------------- The TRACE mode ------------------- With the TRACE function in operation, you will see messages indicating that operations are successful - possibly followed by messages indicating that an operation has failed. This is because many NetBIOS commands are performed in two steps - the first step being the submission of a request to the NetBIOS driver. The driver acknowledges that it has received the request (hence the "success" message). After the operation has been completed, NetBIOS notifies the Netcom control as to the final status of the operation. This status may be "success" or "failure" and is reported back to the application (and directly to the screen if the TRACE function is active). You normally disable the TRACE function in your application before distributing it. ----------------------- Asynchronous Operations ----------------------- Certain NetBIOS operations do not happen instantly. A request to add a new name to the name table is time consuming (perhaps 5 seconds or more). This request is handled synchronously by the Netcom control. It does not return control to your application until the name has been added or the attempt fails. The Netcom control has been designed with consideration for efficient operation of your workstation and ease of programming. There are "tradeoffs" between asynchronous vs. synchronous operations. Synchronous operations are easier for your application to deal with, but require suspending all execution in your application until the operation completes. Asynchronous operations allow your application to do other work while a request is being processed, but are more difficult for your application to work with - you have to handle the events that are sent to the Netcom control. ------------------------------- Using the NetCom Control ------------------------------- The first operation your application needs to do is to send the "Initialize" command to the control. This lets it detect the NetBIOS and set internal variables for use of the NetBIOS layer. The next step is to set appropriate values for the network operations you wish to perform. These are described above in the section on messages you can send to the control. You do not have to do anything to shut down network operations. When the NetCom window is destroyed, it automatically cancels all requests that are outstanding (if any). This occurs when your application terminates or you destroy the NetCom control window (or a window or dialog box that contains it). ------------- NetBIOS names ------------- NetBIOS uses names to identify the sender and receiver of data sent over the network (or within the same workstation). Names are also used to locate network adapters. There are two types of names: UNIQUE names, and GROUP names. Both are exactly 16 characters long. The NetCom control automatically pads an name you specify that is shorter than 16 characters WITH BLANKS. You should be aware that IBM reserves the letters "IBM" for the first three characters of any name, and the characters 0x00 through 0x1F (hex) for the 16th character. You are free to use any other combination of characters. If you register a unique name, you are the only workstation on the network that owns that name. Anyone else (including you) will encounter a NetBIOS error if they attempt to register this name. GROUP names are unique within the same workstation, but can be registered by other workstations. Group names are convenient for communication between several workstations. Any names must be registered by you before you attempt to use the name as an identification of your workstation to another workstation. The NetCom control keeps two names internally - a "Local Name" and a "Remote Name". The local name is used for commands that require an identifier for the originator or receiver of a message. The remote name is used as an identifier for the remote workstation you are communicating with. The remote name is also used as an identifier for adapters in commands that return information about network adapters. For your local adapter, this name is always "*". Specifying a NetBIOS name will address the adapter on the network that has registered that name. You can add and delete NetBIOS names. Be aware that deleting a name that is in use by another application on your workstation will disturb network communications. A special NetBIOS name is the "Permanent Name". This is the set of characters that is "burned in" to your network adapter. This name is returned in the call to the initialization operation in the NetCom control. You do not normally need to use the permanent name, which is unique for all manufactured network adapters. ----------------------- Datagrams ----------------------- Datagrams are "one-way" communications. The sender sends the datagram to all workstations that have registered the name specified by the senders remote name. Any workstations that have register this names (unique or group) and have established a "Receive Datagram" request will receive the datagram. There is no way the sender can tell if any workstations actually receive the datagram. This mechanism is commonly used to broadcast messages to workstations (such as "Network being shut down"). ----------------------- Sessions ----------------------- Sessions provide a means for guaranteed delivery of data between workstations. To establish a session with another workstation, the sending workstation has to register a NetBIOS name as a local name and post a "Call" for a a workstation against a name specified as a remote name (which does not need to be registered by the listener). The receiving workstation has to post a "Listen" for the name it has specified as a remote name, which must match the local name registered by the sender. The receiving workstation must also use a local name that matches the remote name specified by the sender. It is important that the listen is set up on the receiving workstation before the call is attempted on the sending workstation. Otherwise, the session will not be established. It works kind of like a duplex "caller ID" - both workstations have to accept each others names before a session will be established. Once a session is set up (both parties receive an asynchronous notification message, communication can take place. The notification message returns a session number to each workstation (this number is not necessarily the same on both workstations). The application uses this number thereafter to refer to the session. With the session in operation, either party can post a "Receive" or "Send" command. Both of these are asynchronous (notification messages are sent to the application to indicated completion). Completion of an operation is an indication to set up another send or receive. The session is terminated when either party issues a "Hangup" command, which also results in a notification message being sent to the application. It is possible to have several sessions in operation concurrently. However, it is up to the application to keep track of the session numbers. The NetCom control only keeps track of two session numbers: the last one that was established as a result of a "Listen", and the last one that was established as a result of a "Call". To manage multiple sessions, your application has to set the session number in the NetCom control before using the session. ============================= Additional Information ============================= For more information, consult: C Programmers Guide to NetBIOS, IPX, and SPX by W. David Schwaderer, SAMS Publishing, a division of Prentice Hall Computer Publishing, 11711 North College, Carmel, Indiana 46032, USA ================================================================ Northeast Data Corp. 2117 Buffalo Rd., Suite 290 Rochester, NY 14624 716-247-5934 (phone & FAX) ================================================================ May 3, 1994